home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / telecomm / stadel / stadel2.zoo / document / nethack.doc < prev    next >
Encoding:
Text File  |  1989-08-11  |  13.4 KB  |  362 lines

  1.                                NETHACK.DOC
  2.                      How the networker really works
  3.  
  4.                                 Hue, Jr.
  5.                       (rewritten for STadel by Orc)
  6.  
  7.     This document provides a Utopian view of the Citadel auto 
  8.     networking protocol -- it ignores possible foulup points, and 
  9.     generally assumes that the gremlins of the world don't exist, and 
  10.     are gonadless in any case.  Irrelevant complexities and gremlins
  11.     are covered in following sections.  
  12.  
  13. 1) AN OVERVIEW OF A TYPICAL SESSION
  14.  
  15.                 [make the call]
  16.                   |
  17.             [identify network mode]
  18.                   |
  19.                [identify caller]
  20.                   |
  21.                [select options]
  22.                   |
  23.       +---------------------> + <----------------+
  24.       |              |             |
  25.       |           [send a command]         |
  26.       |             / \             |
  27.       +-- [accepted, process]   [refused] -------+
  28.                   .
  29.                   .
  30.           [become slave if rolereverse command]
  31.           [hangup if hangup command]
  32.  
  33. 2) IDENTIFYING NETWORK CALLERS
  34.  
  35.     This is how the master tells the slave that it's actually a
  36.     network caller with a minimum of fuss and bother.  
  37.  
  38.  
  39.          master        |         slave
  40.          ------        |         -----
  41.              Systems detect carrier
  42.                 |
  43.     Send following 3 bytes:    |    If a <7> byte is received,
  44.          7            |    look for the following 2
  45.          13         |    bytes:
  46.          69         |        13
  47.     and wait 4 seconds.     |        69
  48.     If have not received a    |     If these bytes are received,
  49.     correct response (see    |     send back the following:
  50.     slave column), then        |        ~7
  51.     resend the above 3 bytes.    |        ~13
  52.     This looping process should    |        ~69
  53.     only be repeated 20 times.    |    And then wait for an ACK. If
  54.     If, on the 20th try, still    |    one isn't received in 5 seconds,
  55.     have not received a correct    |    return to what the system was
  56.     response, HANGUP.        |    doing before it detected carrier.
  57.     If have received a correct    |
  58.     response, send an ACK.    |
  59.                 |
  60.  
  61.     So, essentially, the master waits a second, and then sends a 3 
  62.     byte sequence to the slave.  When the slave receives those 3 
  63.     bytes successfully, it replies with the logical negation of those
  64.     3 bytes.  The master then sends an ACK back, indicating that the
  65.     call is stabilized.  If 20 times the protocol fails, then the
  66.     master hangs up, assuming something was wrong.  
  67.  
  68.  
  69. 2.1) CALLER IDENTIFIES ITSELF
  70.  
  71.  
  72.     After determining that this is really* a network call, both the 
  73.     master and the slave will drop into Xmodem for passing data back
  74.     and forth.  Therefore, the next byte originates with the slave,
  75.     and that byte is the startup NAK.  The master sends, in this
  76.     order, nodeid, nodename, and the password (if any) it needs to get
  77.     access to the other system.  
  78.  
  79.     nodeid, nodename, password:  Are normal null-terminated C strings.
  80.  
  81.     So, for example, let's say that a system using the nodename 
  82.     "buffalo" and with a nodeId of "US 612 477 0927" called some other
  83.     system.  After the call was stabilised, buffalo would send an 
  84.     identification packet like this to the other system:  
  85.  
  86.              Id        name
  87.         US 612 477 0927<0>Buffalo<0><0>[nulls]
  88.  
  89.     If `Buffalo' is calling a system that needs the password
  90.     `Gloopza', the slave's buffer would look like this 
  91.  
  92.              ID            name     password
  93.         US 612 477 0927<0>Buffalo<0>Gloopza<0>[nulls]
  94.  
  95. 2.2) COMMAND REQUESTS
  96.  
  97.     So, what happens next?  It's a loop, in which the master tells 
  98.     the slave that he wants to do thus-and-so, the slave responds 
  99.     with either "Fine, let's get on with it," or "Nope, [reason]".  
  100.  
  101.     In more detail, it looks like this.  First, remember that all 
  102.     communication is via Xmodem.  A 'complete' command is a 1-byte 
  103.     command followed by 0 to 4 null terminated strings, followed by a 
  104.     null byte.  Currently, the strings can only be 19 characters long.
  105.     So, for instance, if we were to send only a single byte command,
  106.     the sector received by the slave would look like this:  
  107.  
  108.               <command-byte><0>[rest of sector, irrelevant]
  109.  
  110.     A command that also needs to send, say, two strings to the slave
  111.     would look like this:  
  112.  
  113.      <command-byte><string1><string2><0>[rest of sector, irrelevant]
  114.  
  115.     Where string1 and string2 are null-terminated.  These nulls (for 
  116.     the strings) should not* be mistaken for the end of command null!  
  117.  
  118.     So, the slave has received the command.  At this point, the slave
  119.     must decide if he wants to (or can) execute the command requested
  120.     by the master.  If he can, he just sends back (via WC) one byte,
  121.     called GOOD, and then does what the command implies is next.  
  122.  
  123.     If, for any number of reasons, he can't, he should then send back
  124.     one byte, called BAD, and a null-terminated string (< 126 
  125.     characters) that is simply text that tells the master why he can't
  126.     execute, e.g., facility not supported, this room doesn't exist,
  127.     etc.  If BAD is sent back, then the master does the next thing on
  128.     his list of things to do.  
  129.  
  130.     BAD and GOOD are the boolean values FALSE and TRUE, respectively.  
  131.     If the reply byte is nonzero, it implies a GOOD response.  
  132.  
  133. 2.3) NET MESSAGE FORMAT
  134.  
  135.     The format for all messages on the net consists of a collection 
  136.     of C strings (text followed by a null) that represents all the
  137.     data associated each message.  Each field is identified by the
  138.     first character of text in that field, and each identifier is
  139.     unique.  The fields may come in any order, with the exception that
  140.     the Message text itself is the last field.  Any data following the
  141.     null byte that ends the Message field is assumed to be part of the
  142.     next message, or the almost inevitable garbage that occurs in the
  143.     last sector of a WC transfer.  
  144.  
  145.     All data is straight ASCII, ended with a null byte, including 
  146.     those fields that could* be encoded in binary.  
  147.  
  148.     The following fields and identifiers are currently supported.  
  149.  
  150.     Identifier    Data                    Max Length
  151.     ----------    ----                    ----------
  152.     'A'    Author of current message.        125
  153.     'D'    Date on which message was written.    19
  154.     'I'    #organization string for the system    39
  155.         where this message originated.
  156.     'N'    Name of system which message was    9*
  157.         written on.
  158.     'O'    ID of system which message was written    19
  159.         on (i.e., "US 612 866 1804").
  160.     'R'    Room which message was originally    19
  161.         written in.
  162.     'T'    Recipient of message (normally for    125
  163.         private Mail).
  164.     'C'    Time message was written.        19
  165.     'J'    Subject of message.            79
  166.     '#'    Usenet-style message-ID            79
  167.     'M'    Message text.                9999
  168.     'Z'    Network routing code, in the form    21
  169.         @<sigchar><message-id of routing system>
  170.  
  171.     ----------
  172.     * This field is actually 19 characters, but it is recommended to 
  173.     only use the first 9.  
  174.  
  175.     So, a message on Pell (nodeId US 504 588 1258, nodeName `Pell', 
  176.     organization ` (what's all this then?)') that looks like this:  
  177.  
  178.         86Feb01 @ 10:01 from Guido in Q>
  179.         This is a test.
  180.  
  181.     would look like this when being sent across the net:  
  182.  
  183.     D86Feb01<0>C10:01<0>NPell<0>Iwhat's all this then?<0>
  184.     OUS5045881258<0>AGuido<0>RQ<0>Z@LUS5045881258<0>
  185.     MThis is a test<LF><0>
  186.  
  187. 2.4) ROOMSHARING
  188.  
  189.     Citadel nodes network by sharing one or more rooms.  Any Citadel 
  190.     node can choose to keep an image of any public room on any other 
  191.     Citadel node (subject to willingness to foot the phone bills, of 
  192.     course!).  The procedure in essence simply involves calling the 
  193.     imaged node up periodically and copying any new messages in the 
  194.     imaged room into the local image.  
  195.  
  196.     Complexities arise primarily from the possibility of densely 
  197.     connected networks:  one does not wish to accumulate multiple
  198.     copies of a given message, which can easily happen.  Nor does one
  199.     want to see old messages percolating indefinitely through the
  200.     system.  
  201.  
  202.     STadel 3.3a uses the following `brute-force' method of ensuring 
  203.     that this problem doesn't occur:  Each networking system will have
  204.     a file containing the date of the most recent message from every 
  205.     system that shares a given room.  If messages come into this room 
  206.     that are older than the date of the last message, they will be 
  207.     rejected.  
  208.  
  209. 3) CURRENTLY SUPPORTED FACILITIES
  210.  
  211.     HANGUP<0>:  This command is a simple 1-byte command that tells 
  212.     the slave to hang up.  Upon receipt, the slave doesn't bother 
  213.     with replying to the master -- he just hangs up.  Obviously, the 
  214.     master should have completed all other commands by now.  
  215.  
  216.         HANGUP ->
  217.            <- (slave hangs up)
  218.  
  219.  
  220.     MAIL <1>:  This is simply a request for the slave to accept for
  221.     delivery to users on the slave's system of mail from the master.  
  222.  
  223.         MAIL ->
  224.          <- reply GOOD
  225.         mail ->
  226.  
  227.  
  228.     RECEIVE_SHARED_ROOMS <5>:  Send new netmessages to the other 
  229.     system.  This command will be rejected if both systems do not have
  230.     the room and aren't both sharing it with the other system.  The 
  231.     format of the command is 
  232.  
  233.     <RECEIVE_SHARED_ROOMS>room<0>....
  234.  
  235.     and it is followed by a single file that contains all the new
  236.     shared messages for the room in question.  The messages in this
  237.     file are in the usual network message format and are separated by
  238.     $FF characters (i.e;  <message>$FF<message>$FF<message>...) The
  239.     receiving system leaves the messages alone, except for the Z
  240.     field, which is converted to Z@H<nodeid> if the master has this
  241.     room set up as a backbone with the callee, and Z@L<nodeid>
  242.     otherwise.  
  243.  
  244.     The slave determines what to send in the following way:  All 
  245.     messages that originated on the slaves' system are sent, as well 
  246.     as all messages that have a Z@H field on the master's system.  If 
  247.     the slave has set the room up as a backbone with the master, all 
  248.     Z@L messages will be sent as well.  
  249.  
  250.  
  251.     CHECK_MAIL <6>:  This command requests that STadel checks to see 
  252.     if all the netmail that was sent this session is valid.  The 
  253.     slave will check all the mail that came in and send back a single 
  254.     file containing info for each piece of mail that could not be 
  255.     delivered.  The file consists of (surprise!) null-terminated
  256.     strings set up like 
  257.  
  258.     <reason-char>author<0>dest<0>date @ time<0>
  259.  
  260.     The reason-char can be 1 (no such person/system found) or 2 (no 
  261.     recipient?).  Any other failure and the reason-char will be set to
  262.     99.  
  263.  
  264.     If all the mail was correctly addressed, a null file will be 
  265.     returned.  
  266.  
  267.  
  268.     SEND_FILE <7>:  This command sends a file to the slave, provided
  269.     the slave has enough room in its' network receipt directory.  The
  270.     format of the command is 
  271.  
  272.     <SEND_FILE>filename<0>junk<0>size<0>...
  273.  
  274.     IF the command is accepted, the file is sent.  
  275.  
  276.     SEND_FILE file ->
  277.                <- reply GOOD
  278.     file           ->
  279.  
  280.  
  281.     OPTIONS <11>:  Tell the slave what options the master supports.  
  282.     The slave will reply GOOD if it supports those options.  The
  283.     format of the options command is:  
  284.  
  285.     <OPTIONS>options<0>...
  286.  
  287.     OPTIONS<opt> ->
  288.             <- reply GOOD<opt-supported>
  289.     ... networking continues via
  290.     ... new protocol
  291.  
  292.     The reply is not a normal GOOD reply, because the slave will pass
  293.     back the list of options supported.  
  294.  
  295.     The following characters are defined for the options:  
  296.     y - Use Ymodem for networking
  297.     w - Use WXmodem for networking
  298.     k - Use Kermit for networking
  299.     z - Use Zmodem for networking
  300.     c - compress things before transferring them.
  301.  
  302.     For example, if a system that supports wxmodem and ymodem calls a 
  303.     system that only supports ymodem, the exchange would be like so:  
  304.  
  305.     OPTIONS<wy> ->
  306.             <- reply GOOD<y>
  307.     ... networking continues via
  308.     ... ymodem.
  309.  
  310.     The standard format for the options string is
  311.     <proto-list>[,<modifiers>].  If, for instance, your system wanted
  312.     to network in wxmodem or ymodem, plus it supports compressed
  313.     transfers, it would send an option string of <wy,c> to the
  314.     receiver.  If the receiver can handle compression, it would 
  315.     return <y,c>.  
  316.  
  317.  
  318.     BATCH_REQUEST <13>:  Request files from the slave.  This command 
  319.     asks for files from a specified room on the slave.  The format of 
  320.     the command is:  
  321.  
  322.     <BATCH_REQUEST>room<0>filespec<0>[nulls]
  323.  
  324.     If the command is accepted, the files are sent back immediately 
  325.     via `ymodem batch' form (header block, then file, null header to 
  326.     terminate.) The header block contains the filename
  327.     (null-terminated) and the size of the file in bytes (ascii string,
  328.     null terminated) 
  329.  
  330.     BATCH_REQUEST ->
  331.             <- GOOD
  332.             <- header0
  333.             <- file0
  334.             <- header1
  335.             <- file1
  336.                .
  337.                .
  338.                .
  339.             <- [null]
  340.  
  341.     Note that the transfer protocol used will be whatever protocol is
  342.     active at this time.  If the protocol being used has an alternate 
  343.     way to do file batching (zmodem, kermit), that will be used
  344.     instead of the ymodem form.  
  345.  
  346.  
  347.     ROLE_REVERSE <201>:  Reverse master/slave roles so that the slave
  348.     may do its half of the networking.  This may only be done once,
  349.     because of citadel-86 restrictions.  If the slave doesn't want to
  350.     role-reverse, it will hang up the phone on the master.  
  351.  
  352.     ROLE_REVERSE ->
  353.              <- reply GOOD
  354.              <- commands
  355.  
  356.  
  357.     Two other command bytes are reserved for future use:  
  358.  
  359.     BATCH_SEND<12>:  Send files to slave via ymodem batch 
  360.     REMOTE_CMD<10>:  execute a command remotely, return output via WC 
  361.  
  362.